# Snow CLI Usage Documentation - Skills Command Detailed Guide

Skills is a powerful extension feature of Snow CLI that allows you to create and use specialized knowledge bases and toolkits. Each skill contains professional knowledge and practical tools in specific domains, which can be invoked in conversations through the `skill-execute` tool.

## Skills Overview

The Skills feature of Snow CLI is fully compatible with **Claude Code Skills**. You can:

- Create custom skills to encapsulate domain-specific knowledge and tools
- Reuse common task patterns and best practices
- Share skills across different projects
- Restrict tool access permissions for skills
- Create standardized development processes for teams

### Skill Types

Skills are mainly divided into the following categories:

- **Tool Skills**: Provide encapsulation and usage methods for specific tools (e.g., slack-gif-creator)
- **Knowledge Skills**: Contain professional knowledge and best practices in specific domains
- **Template Skills**: Provide reusable code, document, or configuration templates
- **Workflow Skills**: Define standardized task execution processes

## Skill Structure

Each skill is a directory containing the following standard structure:

```
skill-name/
├── SKILL.md          # Main document (required)
├── core/             # Core code modules
│   ├── __init__.py
│   ├── main.py       # Main logic
│   └── utils.py      # Utility functions
├── templates/        # Template files
│   ├── template1.md
│   └── template2.txt
├── scripts/          # Auxiliary scripts
│   ├── setup.sh
│   └── process.py
├── requirements.txt  # Dependency list
└── LICENSE.txt       # License file
```

### SKILL.md Main Document

The main document is the core of a skill, containing:

- **YAML Front Matter**: Defines skill name, description, allowed tools, etc.
- **Detailed Instructions**: Skill functionality, usage methods, API reference
- **Code Examples**: Code snippets showing how to use the skill
- **Best Practices**: Usage tips and precautions

````markdown
---
name: skill-name
description: Detailed description of the skill
allowed-tools: tool1, tool2, tool3
license: Complete terms in LICENSE.txt
---

# Skill Title

## Function Description

Detailed explanation of the skill's functionality and purpose...

## Usage Methods

```python
# Code examples
```

## API Reference

### Function Name

Description of the function's purpose and parameters...

## Best Practices

Precautions and best practices when using the skill...
````

## Skill Locations

Skills can come from three locations:

- **CLI Built-in (builtin)**: shipped with the Snow CLI package (for example `bundle/skills/`)

  - No manual install required
  - Version-locked with the installed CLI
  - Current built-in skill: `snow-docs` (official usage docs)

- **Global Location**: `~/.snow/skills/`

  - Available in all projects
  - Suitable for general, cross-project skills

- **Project Location**: `.snow/skills/`
  - Only available in the current project
  - Suitable for project-specific skills

**Priority**: project > global > builtin. Higher-priority skills override lower-priority ones with the same name.

### Built-in skill: snow-docs

Snow CLI includes a built-in skill `snow-docs` so the agent can answer Snow setup/troubleshooting questions from official docs. It works with these read-only tools:

- `snow-docs-list`
- `snow-docs-search`
- `snow-docs-get`

Disable the skill via `disabledSkills`, or disable the docs tool service via `disabledBuiltInServices`. See: [Official Docs Tools (snow-docs)](./28.Official%20Docs%20Tools%20snow-docs.md).

## Creating Skills

Use the `/skills` command to create new skills:

1. Type `/skills` to open the skill creation dialog
2. Enter a skill name (lowercase letters, numbers, hyphens, max 64 characters)
3. Enter a skill description
4. Select storage location (global or project)
5. Confirm creation

After creation, the system automatically generates:

- SKILL.md (main document)
- Necessary directory structure
- Basic template files

### Skills List & Updates

Use `/skills -l` to open the skills list panel, where you can view, enable/disable all installed skills, and update skills installed from GitHub.

Panel shortcuts:

| Shortcut                  | Action                                                   |
| ------------------------- | -------------------------------------------------------- |
| `↑` / `↓`                 | Navigate the skills list                                 |
| `Tab` / `Space` / `Enter` | Enable/disable the selected skill                        |
| `U`                       | Update the selected GitHub skill                         |
| `A`                       | Update all GitHub skills (downloads each repo only once) |
| `ESC`                     | Close panel (press ESC during update to cancel)          |

The update process has a 120-second timeout to prevent network requests from hanging indefinitely. After updating, the skills list auto-refreshes if any skill versions changed.

## Using Skills

### Use `/skills-` to open the Skills picker (inject into the input)

`/skills-` is a shortcut command (similar to `/agent-` and `/todo-`) that opens a picker panel. It lets you select an existing skill and inject its content into the current input box as an injection block, so you can include that skill prompt in your next message.

How it differs from `/skills`:

- `/skills`: creates a new skill template (generates the directory and `SKILL.md`, etc.).
- `/skills-`: selects from existing skills and injects the skill content into the input (does not create files).

How to open:

- Type `/skills-` in the input and press Enter; or pick `skills-` from the command panel (Enter).

Panel interactions (default behavior):

- Up/Down: change selected skill (wrap-around).
- Tab: toggle focus between the "search" field and the "append" field.
- Enter: confirm selection and inject.
- Esc: close the panel and return to input.

What gets injected (full internal text):

- An injection block starting with `# Skill: <skill-id>` and ending with `# Skill End`.
- In the input UI it is rendered as a placeholder: `[Skill:<skill-id>] ` (note the trailing space so you can continue typing).
- When you send the message, the full injection block is sent (not just the placeholder).

How "append" works:

- If the skill markdown contains the `$ARGUMENTS` placeholder, it will be replaced with the append text.
- If `$ARGUMENTS` is not present, a `[User Append]` block will be appended (only when append is non-empty).

Notes:

- The injected end marker `# Skill End` must end with a newline. Otherwise, if you keep typing after the placeholder, it may get glued to the end marker and cause display masking to collapse unintended text.
- Skill sources are CLI built-in skills, `.snow/skills/` (project), and `~/.snow/skills/` (global). When IDs collide, priority is project > global > builtin.

### Invoking in Conversations (direct tool invocation)

Use the `skill-execute` tool to invoke skills:

```

skill: "skill-name"

```

After invocation, you will see:

```

<command-message>The "skill-name" skill is loading</command-message>

```

Subsequently, the skill content will expand, providing detailed guidance and usage instructions.

### Usage Examples

#### slack-gif-creator Skill Example

This is a complete skill example for creating animated GIFs suitable for Slack:

```python
# Load the skill
skill: "slack-gif-creator"

# The skill will provide detailed usage guidance, including:
# - Slack's GIF requirements (dimensions, framerate, colors, etc.)
# - How to use the GIFBuilder tool class
# - Animation effect implementation (shake, pulse, bounce, etc.)
# - Optimization techniques

# For example, creating an animated GIF
from core.gif_builder import GIFBuilder
from PIL import Image, ImageDraw

# Create builder
builder = GIFBuilder(width=128, height=128, fps=10)

# Generate frames
for i in range(12):
    frame = Image.new('RGB', (128, 128), (240, 248, 255))
    draw = ImageDraw.Draw(frame)

    # Draw animation
    # ... drawing code ...

    builder.add_frame(frame)

# Save optimized GIF
builder.save('output.gif', num_colors=48, optimize_for_emoji=True)
```

## Skill Management

### Listing Available Skills

All available skills are listed in the `skill-execute` tool description, including:

- Skill name
- Skill description
- Skill location (global/project)

### Deleting Skills

Delete custom skills using the `-d` parameter:

- **Delete global skill**: `/skill-name -d` (execute in non-project directory)
- **Delete project skill**: `/skill-name -d` (execute in project directory)

The system automatically identifies the skill location and deletes the corresponding files.

### Skill Restrictions

You can restrict tool access for skills through the `allowed-tools` field:

```yaml
---
name: restricted-skill
description: Skill with restricted tool access
allowed-tools: filesystem-read, filesystem-edit, terminal-execute
---
```

This ensures that skills can only use specified safe tools, improving system security.

## Skill Development Best Practices

### 1. Documentation Writing

- Use clear structure and headings
- Provide rich code examples
- Include common problems and solutions
- Explain dependencies and environment requirements

### 2. Code Organization

- Put core logic in `core/` directory
- Use modular design
- Provide clear APIs
- Add appropriate error handling

### 3. Templates and Scripts

- Provide common templates in `templates/` directory
- Provide auxiliary scripts in `scripts/` directory
- Ensure scripts have executable permissions
- Provide usage instructions

### 4. Tool Restrictions

- Only allow necessary tools
- Avoid high-risk operations
- Use tool restrictions to improve security
- Document restriction reasons

### 5. Version Control

- Add version information to skills
- Record change logs
- Use semantic versioning
- Maintain backward compatibility

## Common Skill Examples

### 1. Code Generation Skill

```markdown
---
name: code-generator
description: Code generation templates and best practices
allowed-tools: filesystem-read, filesystem-edit, terminal-execute
---
```

Provides common code generation templates and patterns.

### 2. Document Template Skill

```markdown
---
name: doc-templates
description: Collection of document and comment templates
allowed-tools: filesystem-read, filesystem-edit
---
```

Provides templates for README, API documentation, comments, etc.

### 3. Test Case Skill

```markdown
---
name: test-templates
description: Test case templates and testing tools
allowed-tools: filesystem-read, filesystem-edit, terminal-execute
---
```

Provides templates for unit tests, integration tests, etc.

### 4. Deployment Script Skill

```markdown
---
name: deploy-scripts
description: Automated deployment scripts and processes
allowed-tools: filesystem-read, filesystem-edit, terminal-execute
---
```

Provides CI/CD deployment scripts and best practices.

## Compatibility with Claude Code Skills

The Skills feature of Snow CLI is fully compatible with Claude Code Skills:

- **Same Invocation Method**: Use `skill: "skill-name"` to invoke
- **Same Structure Requirements**: SKILL.md as main document
- **Same Metadata Format**: YAML front matter
- **Same Tool Restrictions**: Supports allowed-tools field
- **Fully Compatible Ecosystem**: Can directly use existing Claude Code Skills

This means you can directly use in Snow CLI:

- Official Claude Code Skills provided by Anthropic
- Community-created compatible skills
- Your own created Snow CLI skills

## Skill Security

### Tool Permission Control

Strongly recommend specifying allowed tool list for each skill:

```yaml
---
name: safe-skill
description: Example of safe skill
allowed-tools: filesystem-read, filesystem-edit
---
```

### Sensitive Operations

Avoid including in skills:

- Direct system calls
- Sensitive information (keys, passwords, etc.)
- Destructive operations (deletion, formatting, etc.)

### Code Review

Regularly review skill code:

- Check for security vulnerabilities
- Verify tool usage
- Update dependency versions
- Remove deprecated functionality

## Troubleshooting

### Skill Not Found

**Symptom**: "Skill not found" error when invoking skill

**Solutions**:

1. Check skill name spelling
2. Confirm skill is correctly installed
3. Verify skill location (global/project)
4. Check if SKILL.md file exists

### Tool Permission Error

**Symptom**: Insufficient tool permissions when running skill

**Solutions**:

1. Check allowed-tools configuration
2. Verify tool name spelling
3. Add necessary tools in permission management
4. Contact administrator to grant permissions

### Missing Dependencies

**Symptom**: Module not found error when running skill

**Solutions**:

1. Check requirements.txt
2. Install missing dependencies: `pip install -r requirements.txt`
3. Verify Python environment
4. Check virtual environment activation status

### Syntax Errors

**Symptom**: Syntax errors in skill document or code

**Solutions**:

1. Check YAML front matter format
2. Verify Markdown syntax
3. Check code syntax
4. Use code formatting tools

## Related Configuration

- [Command Panel Guide](./09.0.Command%20Panel%20Guide.md) - Basic command introduction
- [MCP Configuration](./14.MCP%20Configuration.md) - MCP service configuration
- [Official Docs Tools (snow-docs)](./28.Official%20Docs%20Tools%20snow-docs.md) - Built-in official docs skill/tools
- [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Security tool configuration
- [Sub-Agent Configuration](./05.Sub-Agent%20Configuration.md) - Sub-agent tool configuration

## Advanced Usage

### Skill Combination

You can combine multiple skills:

```python
# First invoke code generation skill
skill: "code-generator"

# Then invoke test template skill
skill: "test-templates"

# Finally invoke deployment script skill
skill: "deploy-scripts"
```

### Dynamic Skills

Skills support dynamic loading, taking effect immediately after modification:

1. Edit skill files
2. Save changes
3. Reinvoke skill

No need to restart the application.

### Skill Debugging

Use the following methods to debug skills:

1. Check skill directory structure
2. Verify SKILL.md format
3. Test core code modules
4. View error logs

## Community and Sharing

### Skill Sharing

You can share your skills with the community:

1. Ensure code quality and complete documentation
2. Add appropriate license
3. Create usage examples
4. Publish to skill repository

### Skill Discovery

Ways to find useful skills:

1. Check official skill list
2. Search community skill library
3. Ask other users for recommendations
4. Customize based on project needs

## Summary

The Skills feature of Snow CLI is a powerful extension system that allows you to:

- **Encapsulate Professional Knowledge**: Package domain knowledge into reusable skills
- **Standardize Processes**: Establish unified development processes for teams
- **Improve Efficiency**: Reduce repetitive work and focus on innovation
- **Ensure Quality**: Use validated best practices
- **Promote Collaboration**: Share experiences and skills among team members

By using Skills reasonably, you can significantly improve development efficiency and code quality, while establishing more standardized and efficient development processes.